Auto Index

The autoindex directive enables NGINX to automatically generate a directory listing when a client requests a directory URL that does not contain an index file.

In other words:

Instead of returning a 403/404 error for a directory with no index, NGINX lists all files and subdirectories.

Example: http://example.com/downloads/

If /downloads/ has no index.html and autoindex on is enabled, NGINX shows:

• File1.zip
• File2.pdf
• Subfolder/

Syntax

autoindex on | off;
autoindex_format html | json;

Parameters

Parameter	Description
on	Enable directory listing
off	Disable directory listing (default)
html	Generate HTML page (default)
json	Generate JSON output (NGINX 1.7+)

Context

autoindex can be used in: http (rare), server, location

Basic Example

server {
    listen 80;
    server_name example.com;

    root /var/www/html/downloads;

    location /downloads/ {
        autoindex on;
    }
}

• Request: http://example.com/downloads/
• /var/www/html/downloads/ contains files:
  • file1.zip
  • file2.pdf
  • images/

NGINX returns HTML directory listing of all files and folders

Autoindex with Custom Format (JSON)

location /files/ {
    root /var/www/html;
    autoindex on;
    autoindex_format json;
}

Request: http://example.com/files/

NGINX returns a JSON array:

[
  { "name": "file1.txt", "type": "file" },
  { "name": "images", "type": "directory" }
]

Useful for API-driven directory access.

Combining autoindex with index

location /downloads/ {
    index index.html;
    autoindex on;
}

Behavior

• If index.html exists → served
• If no index → directory listing generated

Styling Autoindex Listings

NGINX provides additional directives for better listings:

location /downloads/ {
    autoindex on;
    autoindex_exact_size off;  # Show sizes in KB/MB
    autoindex_localtime on;    # Show modification times in local timezone
}

Example listing:

Name	Last modified	Size
file1.zip	2026-01-19 10:30	1.2M
file2.pdf	2026-01-18 16:20	500K

Security Considerations

Warning: Directory listings can expose sensitive files.

Best Practices:

• Only enable autoindex in safe directories (downloads, public assets)
• Disable in application or configuration directories
• Optionally combine with authentication:

location /downloads/ {
    autoindex on;
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Avoid exposing .git, .env, or config files

Using autoindex with try_files

location /files/ {
    root /var/www/html;
    try_files $uri $uri/ =404;
    autoindex on;
}

• try_files checks if file exists
• If directory exists and no index → autoindex generates listing
• Else → 404

Example: Production Use Case

server {
    listen 80;
    server_name example.com;

    root /var/www/html;

    location /downloads/ {
        autoindex on;
        autoindex_exact_size off;
        autoindex_localtime on;
        expires 7d;
    }
}

• Publicly available downloads
• User-friendly listing with sizes and timestamps
• Cached by client browsers

Disabling Autoindex Globally

By default, autoindex is off, which is safest for security:

http {
    autoindex off;
}

Only enable per location where needed

Common Mistakes

Mistake	Effect
Enabling autoindex in app root	Exposes sensitive files
Not using index with autoindex	Users see listing instead of homepage
Serving hidden files (.*)	Security risk
Forgetting root or alias	Directory listing fails